Historical updating oE console, Revision 2
updating oE has_console
updating oE key_codes
updating oE KC_LBUTTON
updating oE set_keycodes
updating oE NO_CURSOR
updating oE UNDERLINE_CURSOR
updating oE THICK_UNDERLINE_CURSOR
updating oE HALF_BLOCK_CURSOR
updating oE BLOCK_CURSOR
updating oE get_key
updating oE allow_break
updating oE check_break
updating oE wait_key
updating oE any_key
updating oE maybe_any_key
updating oE prompt_number
updating oE prompt_string
updating oE positive_int
updating oE clear_screen
updating oE get_screen_char
updating oE put_screen_char
updating oE attr_to_colors
updating oE colors_to_attr
updating oE display_text_image
updating oE save_text_image
updating oE text_rows
updating oE cursor
updating oE free_console
updating oE display
Console
Information
has_console
include console.e namespace console public function has_console()
determines if the process has a console (terminal) window.
Returns:
An atom,
- 1 if there is more than one process attached to the current console,
- 0 if a console does not exist or only one process (Euphoria) is attached to the current console.
Comments:
- On Unix systems always returns 1 .
- On Windows client systems earlier than Windows XP the function always returns 0 .
- On Windows server systems earlier than Windows Server 2003 the function always returns 0 .
Example 1:
include std/console.e if has_console() then printf(1, "Hello Console!") end if
key_codes
include console.e namespace console public function key_codes(object codes = 0)
gets and sets the keyboard codes used internally by Euphoria.
Parameters:
- codes : Either a sequence of exactly 256 integers or an atom (the default).
Returns:
A sequence, of the current 256 keyboard codes, prior to any changes that this function might make.
Comments:
When codes is a atom then no change to the existing codes is made, otherwise the set of 256 integers in codes completely replaces the existing codes.
Example 1:
include std/console.e sequence kc kc = key_codes() -- Get existing set. kc[KC_LEFT] = 263 -- Change the code for the left-arrow press. key_codes(kc) -- Set the new codes.
Key Code Names
These are the names of the index values for each of the 256 key code values.
See Also:
KC_LBUTTON
include console.e namespace console public constant KC_LBUTTON
set_keycodes
include console.e namespace console public function set_keycodes(object kcfile)
changes the default codes returned by the keyboard.
Parameters:
- kcfile : Either the name of a text file or the handle of an opened (for reading) text file.
Returns:
An integer,
- 0 means no error.
- -1 means that the supplied file could not me loaded in to a map.
- -2 means that a new key value was not an integer.
- -3 means that an unknown key name was found in the file.
Comments:
The text file is expected to contain bindings for one or more keyboard codes.
The format of the files is a set of lines, one line per key binding, in the form KEYNAME = NEWVALUE. The KEYNAME is the same as the constants but without the "KC_" prefix. The key bindings can be in any order.
Example 1:
-- doskeys.txt file containing some key bindings F1 = 260 F2 = 261 INSERT = 456
set_keycodes( "doskeys.txt" )
See Also:
Cursor Style Constants
In cursor constants the second and fourth hex digits (from the left) determine the top and bottom row of pixels in the cursor. The first digit controls whether the cursor will be visible or not. For example: #0407 turns on the 4th through 7th rows.
Note: Windows only.
See Also:
NO_CURSOR
include console.e namespace console public constant NO_CURSOR
UNDERLINE_CURSOR
include console.e namespace console public constant UNDERLINE_CURSOR
THICK_UNDERLINE_CURSOR
include console.e namespace console public constant THICK_UNDERLINE_CURSOR
HALF_BLOCK_CURSOR
include console.e namespace console public constant HALF_BLOCK_CURSOR
BLOCK_CURSOR
include console.e namespace console public constant BLOCK_CURSOR
Keyboard Related Routines
get_key
<built-in> function get_key()
returns the key that was pressed by the user, without waiting. Special codes are returned for the function keys, arrow keys, and so on.
Returns:
An integer, either -1 if no key waiting, or the code of the next key waiting in keyboard buffer.
Comments:
The operating system can hold a small number of key-hits in its keyboard buffer. get_key will return the next one from the buffer, or -1 if the buffer is empty.
Run the .../euphoria/demo/key.ex program to see what key code is generated for each key on your keyboard.
Example 1:
integer n = get_key() if n=-1 then puts(1, "No key waiting.\n") end if
See Also:
allow_break
include console.e namespace console public procedure allow_break(types :boolean b)
sets the behavior of Control+C and Control+Break keys.
Parameters:
- b : a boolean, TRUE ( != 0 ) to enable the trapping of Control+C and Control+Break, FALSE ( 0 ) to disable it.
Comments:
When b is 1 (true), Control+C and Control+Break can terminate your program when it tries to read input from the keyboard. When b is 0 (false) your program will not be terminated by Control+C or Control+Break.
Initially your program can be terminated at any point where it tries to read from the keyboard.
You can find out if the user has pressed Control+C or Control+Break by calling check_break.
Example 1:
allow_break(0) -- don't let the user kill the program!
See Also:
check_break
include console.e namespace console public function check_break()
returns the number of Control+C and Control+Break key presses.
Returns:
An integer, the number of times that Control+C or Control+Break have been pressed since the last call to check_break, or since the beginning of the program if this is the first call.
Comments:
This is useful after you have called allow_break(0) which prevents Control+C or Control+Break from terminating your program. You can use check_break to find out if the user has pressed one of these keys. You might then perform some action such as a graceful shutdown of your program.
Neither Control+C nor Control+Break will be returned as input characters when you read the keyboard. You can only detect them by calling check_break.
Example 1:
k = get_key() if check_break() then -- ^C or ^Break was hit once or more temp = graphics_mode(-1) puts(STDOUT, "Shutting down...") save_all_user_data() abort(1) end if
See Also:
wait_key
include console.e namespace console public function wait_key()
waits for user to press a key, unless any is pending, and returns key code.
Returns:
An integer, which is a key code. If one is waiting in keyboard buffer, then return it. Otherwise, wait for one to come up.
See Also:
any_key
include console.e namespace console public procedure any_key(sequence prompt = "Press Any Key to continue...", integer con = 1)
displays a prompt to the user and waits for any key.
Parameters:
- prompt : Prompt to display, defaults to "Press Any Key to continue..." .
- con : Either 1 (stdout), or 2 (stderr). Defaults to 1 .
Comments:
This wraps wait_key by giving a clue that the user should press a key, and perhaps do some other things as well.
Example 1:
any_key() -- "Press Any Key to continue..."
Example 2:
any_key("Press Any Key to quit")
See Also:
maybe_any_key
include console.e namespace console public procedure maybe_any_key(sequence prompt = "Press Any Key to continue...", integer con = 1)
displays a prompt to the user and waits for any key. Only if the user is running under a GUI environment.
Parameters:
- prompt : Prompt to display, defaults to "Press Any Key to continue..."
- con : Either 1 (stdout), or 2 (stderr). Defaults to 1.
Comments:
This wraps wait_key by giving a clue that the user should press a key, and perhaps do some other things as well.
Requires Windows XP or later or Windows 2003 or later to work. Earlier versions of Windows or O/S will always pause even when not needed.
On Unix systems this will not pause even when needed.
Example 1:
any_key() -- "Press Any Key to continue..."
Example 2:
any_key("Press Any Key to quit")
See Also:
prompt_number
include console.e namespace console public function prompt_number(sequence prompt, sequence range)
prompts the user to enter a number and returns only validated input.
Parameters:
- st : is a string of text that will be displayed on the screen.
- s : is a sequence of two values {lower, upper} which determine the range of values that the user may enter. s can be empty, {}, if there are no restrictions.
Returns:
An atom, in the assigned range which the user typed in.
Errors:
If puts cannot display st on standard output, or if the first or second element of s is a sequence, a runtime error will be raised.
If user tries cancelling the prompt by hitting Control+Z, the program will abort as well, issuing a type check error.
Comments:
As long as the user enters a number that is less than lower or greater than upper, the user will be prompted again.
If this routine is too simple for your needs, feel free to copy it and make your own more specialized version.
Example 1:
age = prompt_number("What is your age? ", {0, 150})
Example 2:
t = prompt_number("Enter a temperature in Celcius:\n", {})
See Also:
prompt_string
include console.e namespace console public function prompt_string(sequence prompt)
prompts the user to enter a string of text.
Parameters:
- st : is a string that will be displayed on the screen.
Returns:
A sequence, the string that the user typed in, stripped of any new-line character.
Comments:
If the user happens to type Control+Z (indicates end-of-file), "" will be returned.
Example 1:
name = prompt_string("What is your name? ")
See Also:
Cross Platform Text Graphics
positive_int
include console.e namespace console public type positive_int(object x)
clear_screen
<built-in> procedure clear_screen()
clears the screen using the current background color.
Comments:
The background color can be set by bk_color ).
See Also:
get_screen_char
include console.e namespace console public function get_screen_char(positive_atom line, positive_atom column, integer fgbg = 0)
gets the value and attribute of the character at a given screen location.
Parameters:
- line : the 1-base line number of the location.
- column : the 1-base column number of the location.
- fgbg : an integer, if 0 (the default) you get an attribute_code returned otherwise you get a foreground and background color number returned.
Returns:
- If fgbg is zero then a sequence of two elements, {character, attribute_code} for the specified location.
- If fgbg is not zero then a sequence of three elements, {characterfg_color, bg_color}.
Comments:
- This function inspects a single character on the active page.
- The attribute_code is an atom that contains the foreground and background color of the character, and possibly other operating-system dependant information describing the appearance of the character on the screen.
- With get_screen_char and put_screen_char you can save and restore a character on the screen along with its attribute_code.
- The fg_color and bg_color are integers in the range 0 to 15 which correspond to the values in the table:
Color Table
| color number | name |
|---|---|
| 0 | black |
| 1 | dark blue |
| 2 | green |
| 3 | cyan |
| 4 | crimson |
| 5 | purple |
| 6 | brown |
| 7 | light gray |
| 8 | dark gray |
| 9 | blue |
| 10 | bright green |
| 11 | light blue |
| 12 | red |
| 13 | magenta |
| 14 | yellow |
| 15 | white |
Example 1:
-- read character and attributes at top left corner s = get_screen_char(1,1) -- s could be {'A', 92} -- store character and attributes at line 25, column 10 put_screen_char(25, 10, s)
Example 2:
-- read character and colors at line 25, column 10. s = get_screen_char(25,10, 1) -- s could be {'A', 12, 5}
See Also:
put_screen_char, save_text_image
put_screen_char
include console.e namespace console public procedure put_screen_char(positive_atom line, positive_atom column, sequence char_attr)
stores and displays a sequence of characters with attributes at a given location.
Parameters:
- line : the 1-based line at which to start writing.
- column : the 1-based column at which to start writing.
- char_attr : a sequence of alternated characters and attribute codes.
Comments:
char_attr must be in the form {character, attribute code, character, attribute code, ...}.
Errors:
The length of char_attr must be a multiple of two.
Comments:
The attributes atom contains the foreground color, background color, and possibly other platform-dependent information controlling how the character is displayed on the screen. If char_attr has 0 length, nothing will be written to the screen. The characters are written to the active page. It is faster to write several characters to the screen with a single call to put_screen_char than it is to write one character at a time.
Example 1:
-- write AZ to the top left of the screen -- (attributes are platform-dependent) put_screen_char(1, 1, {'A', 152, 'Z', 131})
See Also:
get_screen_char, display_text_image
attr_to_colors
include console.e namespace console public function attr_to_colors(integer attr_code)
converts an attribute code to its foreground and background color components.
Parameters:
- attr_code : integer, an attribute code.
Returns:
A sequence, of two elements -- {fgcolor, bgcolor}
Example 1:
? attr_to_colors(92) --> {12, 5}
See Also:
get_screen_char, colors_to_attr
colors_to_attr
include console.e namespace console public function colors_to_attr(object fgbg, integer bg = 0)
converts a foreground and background color set to its attribute code format.
Parameters:
- fgbg : Either a sequence of {fgcolor, bgcolor} or just an integer fgcolor.
- bg : An integer bgcolor. Only used when fgbg is an integer.
Returns:
An integer, an attribute code.
Example 1:
? colors_to_attr({12, 5}) --> 92 ? colors_to_attr(12, 5) --> 92
See Also:
get_screen_char, put_screen_char, attr_to_colors
display_text_image
include console.e namespace console public procedure display_text_image(text_point xy, sequence text)
displays a text image in any text mode.
Parameters:
- xy : a pair of 1-based coordinates representing the point at which to start writing.
- text : a list of sequences of alternated character and attribute.
Comments:
This routine displays to the active text page, and only works in text modes.
You might use save_text_image and display_text_image in a text-mode graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen.
Example 1:
clear_screen() display_text_image({1,1}, {{'A', WHITE, 'B', GREEN}, {'C', RED+16*WHITE}, {'D', BLUE}}) -- displays: -- AB -- C -- D -- at the top left corner of the screen. -- 'A' will be white with black (0) background color, -- 'B' will be green on black, -- 'C' will be red on white, and -- 'D' will be blue on black.
See Also:
save_text_image, put_screen_char
save_text_image
include console.e namespace console public function save_text_image(text_point top_left, text_point bottom_right)
copies a rectangular block of text out of screen memory.
Parameters:
- top_left : the coordinates, given as a pair, of the upper left corner of the area to save.
- bottom_right : the coordinates, given as a pair, of the lower right corner of the area to save.
Returns:
A sequence, of {character, attribute, character, ...} lists.
Comments:
The returned value is appropriately handled by display_text_image.
This routine reads from the active text page, and only works in text modes.
You might use this function in a text-mode graphical user interface to save a portion of the screen before displaying a drop-down menu, dialog box, alert box, and so on.
Example 1:
-- Top 2 lines are: Hello and World s = save_text_image({1,1}, {2,5}) -- s is something like: {"H-e-l-l-o-", "W-o-r-l-d-"}
See Also:
display_text_image, get_screen_char
text_rows
include console.e namespace console public function text_rows(positive_int rows)
sets the number of lines on a text-mode screen.
Parameters:
- rows : an integer, the desired number of rows.
Platform:
Windows
Returns:
An integer, the actual number of text lines.
Comments:
Values of 25, 28, 43 and 50 lines are supported by most video cards.
See Also:
cursor
include console.e namespace console public procedure cursor(integer style)
selects a style of cursor.
Parameters:
- style : an integer defining the cursor shape.
Platform:
Windows
Comments:
In pixel-graphics modes no cursor is displayed.
Example 1:
cursor(BLOCK_CURSOR)
Cursor Type Constants:
See Also:
free_console
include console.e namespace console public procedure free_console()
frees (deletes) any console window associated with your program.
Comments:
Euphoria will create a console text window for your program the first time that your program prints something to the screen, reads something from the keyboard, or in some way needs a console. On Windows this window will automatically disappear when your program terminates, but you can call free_console to make it disappear sooner. On Unix the text mode console is always there, but an xterm window will disappear after Euphoria issues a "Press Enter" prompt at the end of execution.
On Unix free_console will set the terminal parameters back to normal, undoing the effect that curses has on the screen.
In a Unix terminal a call to free_console (without any further printing to the screen or reading from the keyboard) will eliminate the "Press Enter" prompt that Euphoria normally issues at the end of execution.
After freeing the console window, you can create a new console window by printing something to the screen, calling clear_screen, position, or any other routine that needs a console.
When you use the trace facility, or when your program has an error, Euphoria will automatically create a console window to display trace information, error messages, and so on.
There is a WINDOWS API routine, FreeConsole() that does something similar to free_console. Use the Euphoria free_console because it lets the interpreter know that there is no longer a console to write to or read from.
See Also:
display
include console.e namespace console public procedure display(object data_in, object args = 1, integer finalnl = - 918_273_645)
displays the supplied data on the console screen at the current cursor position.
Parameters:
- data_in : Any object.
- args : Optional arguments used to format the output. Default is 1 .
- finalnl : Optional. Determines if a new line is output after the data. Default is to output a new line.
Comments:
- If data_in is an atom or integer, it is simply displayed.
- If data_in is a simple text string, then args can be used to produce a formatted output with data_in providing the text:format string and args being a sequence containing the data to be formatted.
- If the last character of data_in is an underscore character then it is stripped off and finalnl is set to zero. Thus ensuring that a new line is not output.
- The formatting codes expected in data_in are the ones used by text:format. It is not mandatory to use formatting codes, and if data_in does not contain any then it is simply displayed and anything in args is ignored.
- If data_in is a sequence containing floating-point numbers, sub-sequences or integers that are not characters, then data_in is forwarded on to the pretty_print to display.
- If args is a non-empty sequence, it is assumed to contain the pretty_print formatting options.
- if args is an atom or an empty sequence, the assumed pretty_print formatting options are assumed to be {2}.
After the data is displayed, the routine will normally output a New Line. If you want to avoid this, ensure that the last parameter is a zero. Or to put this another way, if the last parameter is zero then a New Line will not be output.
Example 1:
display("Some plain text") -- Displays this string on the console plus a new line. display("Your answer:",0) -- Displays this string on the console without a new line. display("cat") display("Your answer:",,0) -- Displays this string on the console without a new line. display("") display("Your answer:_") -- Displays this string, -- except the '_', on the console without a new line. display("dog") display({"abc", 3.44554}) -- Displays the contents of 'res' on the console. display("The answer to [1] was [2]", {"'why'", 42}) -- formats these with a new line. display("",2) display({51,362,71}, {1})
Output would be:
Some plain text
Your answer:cat
Your answer:
Your answer:dog
{
"abc",
3.44554
}
The answer to 'why' was 42
""
{51'3',362,71'G'}
|
Not Categorized, Please Help
|
- diff to current revision, view current revision history, backlinks
- Last modified Sep 03, 2019 by _tom
